home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / prtrace.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  24KB  |  679 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #ifndef prtrace_h___
  39. #define prtrace_h___
  40. /*
  41. ** prtrace.h -- NSPR's Trace Facility.                     
  42. **                                                                                  
  43. ** The Trace Facility provides a means to trace application                           
  44. ** program events within a process. When implementing an                            
  45. ** application program an engineer may insert a "Trace" function                    
  46. ** call, passing arguments to be traced. The "Trace" function                        
  47. ** combines the user trace data with identifying data and                           
  48. ** writes this data in time ordered sequence into a circular                        
  49. ** in-memory buffer; when the buffer fills, it wraps.
  50. **                                                                                  
  51. ** Functions are provided to set and/or re-configure the size of                   
  52. ** the trace buffer, control what events are recorded in the                       
  53. ** buffer, enable and disable tracing based on specific user                       
  54. ** supplied data and other control functions. Methods are provided                   
  55. ** to record the trace entries in the in-memory trace buffer to
  56. ** a file.
  57. **                                                                                  
  58. ** Tracing may cause a performance degredation to the application                   
  59. ** depending on the number and placement of calls to the tracing                   
  60. ** facility. When tracing is compiled in and all tracing is                           
  61. ** disabled via the runtime controls, the overhead should be                       
  62. ** minimal. ... Famous last words, eh?                                               
  63. **                                                                                    
  64. ** When DEBUG is defined at compile time, the Trace Facility is                    
  65. ** compiled as part of NSPR and any application using NSPR's                       
  66. ** header files will have tracing compiled in. When DEBUG is not                   
  67. ** defined, the Trace Facility is not compiled into NSPR nor                       
  68. ** exported in its header files.  If the Trace Facility is                         
  69. ** desired in a non-debug build, then FORCE_NSPR_TRACE may be                      
  70. ** defined at compile time for both the optimized build of NSPR                    
  71. ** and the application. NSPR and any application using  NSPR's                     
  72. ** Trace Facility must be compiled with the same level of trace                    
  73. ** conditioning or unresolved references may be realized at link                   
  74. ** time.                                                                           
  75. **                                                                                 
  76. ** For any of the Trace Facility methods that requires a trace                     
  77. ** handle as an input argument, the caller must ensure that the                    
  78. ** trace handle argument is valid. An invalid trace handle                         
  79. ** argument may cause unpredictable results.                                       
  80. **                                                                                 
  81. ** Trace Facility methods are thread-safe and SMP safe.                            
  82. **                                                                                 
  83. ** Users of the Trace Facility should use the defined macros to                     
  84. ** invoke trace methods, not the function calls directly. e.g.                      
  85. ** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
  86. **                                                                                  
  87. ** Application designers should be aware of the effects of
  88. ** debug and optimized build differences when using result of the
  89. ** Trace Facility macros in expressions.
  90. ** 
  91. ** See Also: prcountr.h                                                                                 
  92. **                                                                                  
  93. ** /lth. 08-Jun-1998.                                                                                  
  94. */
  95.  
  96. #include "prtypes.h"
  97. #include "prthread.h"
  98. #include "prtime.h"
  99.  
  100. PR_BEGIN_EXTERN_C
  101.  
  102. /*
  103. ** Opaque type for the trace handle 
  104. ** ... Don't even think about looking in here.
  105. **
  106. */
  107. typedef void *  PRTraceHandle;
  108.  
  109. /*
  110. ** PRTraceEntry -- A trace entry in the in-memory trace buffer
  111. ** looks like this.
  112. **
  113. */
  114. typedef struct PRTraceEntry
  115. {
  116.     PRThread        *thread;        /* The thread creating the trace entry */
  117.     PRTraceHandle   handle;         /* PRTraceHandle creating the trace entry */
  118.     PRTime          time;           /* Value of PR_Now() at time of trace entry */
  119.     PRUint32        userData[8];    /* user supplied trace data */
  120. } PRTraceEntry;
  121.  
  122. /*
  123. ** PRTraceOption -- command operands to
  124. ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
  125. **
  126. */
  127. typedef enum PRTraceOption
  128. {
  129.     PRTraceBufSize,
  130.     PRTraceEnable,              
  131.     PRTraceDisable,
  132.     PRTraceSuspend,
  133.     PRTraceResume,
  134.     PRTraceSuspendRecording,
  135.     PRTraceResumeRecording,
  136.     PRTraceLockHandles,
  137.     PRTraceUnLockHandles,
  138.     PRTraceStopRecording
  139. } PRTraceOption;
  140.  
  141. /* -----------------------------------------------------------------------
  142. ** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
  143. ** 
  144. ** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
  145. ** handle.
  146. ** 
  147. */
  148. #define PR_DEFINE_TRACE(name) PRTraceHandle name
  149.  
  150. /* -----------------------------------------------------------------------
  151. ** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
  152. ** 
  153. ** DESCRIPTION: 
  154. ** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
  155. ** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
  156. ** 
  157. */
  158. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  159. #define PR_INIT_TRACE_HANDLE(handle,value)\
  160.     (handle) = (PRCounterHandle)(value)
  161. #else
  162. #define PR_INIT_TRACE_HANDLE(handle,value)
  163. #endif
  164.  
  165.  
  166. /* -----------------------------------------------------------------------
  167. ** FUNCTION: PR_CreateTrace() -- Create a trace handle
  168. ** 
  169. ** DESCRIPTION:
  170. **  PR_CreateTrace() creates a new trace handle. Tracing is
  171. **  enabled for this handle when it is created. The trace handle
  172. **  is intended for use in other Trace Facility calls.
  173. **  
  174. **  PR_CreateTrace() registers the QName, RName and description
  175. **  data so that this data can be retrieved later.
  176. ** 
  177. ** INPUTS: 
  178. **  qName: pointer to string. QName for this trace handle. 
  179. ** 
  180. **  rName: pointer to string. RName for this trace handle. 
  181. ** 
  182. **  description: pointer to string. Descriptive data about this
  183. **  trace handle.
  184. **
  185. ** OUTPUTS:
  186. **  Creates the trace handle. 
  187. **  Registers the QName and RName with the trace facility.
  188. ** 
  189. ** RETURNS: 
  190. **  PRTraceHandle
  191. ** 
  192. ** RESTRICTIONS:
  193. **  qName is limited to 31 characters.
  194. **  rName is limited to 31 characters.
  195. **  description is limited to 255 characters.
  196. ** 
  197. */
  198. #define PRTRACE_NAME_MAX 31
  199. #define PRTRACE_DESC_MAX 255
  200.  
  201. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  202. #define PR_CREATE_TRACE(handle,qName,rName,description)\
  203.     (handle) = PR_CreateTrace((qName),(rName),(description))
  204. #else
  205. #define PR_CREATE_TRACE(handle,qName,rName,description)
  206. #endif
  207.  
  208. NSPR_API(PRTraceHandle)
  209.     PR_CreateTrace( 
  210.         const char *qName,          /* QName for this trace handle */
  211.         const char *rName,          /* RName for this trace handle */
  212.         const char *description     /* description for this trace handle */
  213. );
  214.  
  215.  
  216. /* -----------------------------------------------------------------------
  217. ** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
  218. ** 
  219. ** DESCRIPTION: 
  220. **  PR_DestroyTrace() removes the referenced trace handle and
  221. ** associated QName, RName and description data from the Trace
  222. ** Facility.
  223. ** 
  224. ** INPUTS: handle. A PRTraceHandle
  225. ** 
  226. ** OUTPUTS: 
  227. **  The trace handle is unregistered.
  228. **  The QName, RName and description are removed.
  229. ** 
  230. ** RETURNS: void
  231. ** 
  232. ** RESTRICTIONS:
  233. ** 
  234. */
  235. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  236. #define PR_DESTROY_TRACE(handle)\
  237.     PR_DestroyTrace((handle))
  238. #else
  239. #define PR_DESTROY_TRACE(handle)
  240. #endif
  241.  
  242. NSPR_API(void) 
  243.     PR_DestroyTrace( 
  244.         PRTraceHandle handle    /* Handle to be destroyed */
  245. );
  246.  
  247.  
  248. /* -----------------------------------------------------------------------
  249. ** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
  250. ** 
  251. ** DESCRIPTION:
  252. ** PR_Trace() makes an entry in the in-memory trace buffer for
  253. ** the referenced trace handle. The next logically available
  254. ** PRTraceEntry is used; when the next trace entry would overflow
  255. ** the trace table, the table wraps.
  256. **
  257. ** PR_Trace() for a specific trace handle may be disabled by
  258. ** calling PR_SetTraceOption() specifying PRTraceDisable for the
  259. ** trace handle to be disabled.
  260. ** 
  261. ** INPUTS:
  262. ** handle: PRTraceHandle. The trace handle for this trace.
  263. ** 
  264. ** userData[0..7]: unsigned 32bit integers. user supplied data
  265. ** that is copied into the PRTraceEntry
  266. ** 
  267. ** OUTPUTS:
  268. **  A PRTraceEntry is (conditionally) formatted in the in-memory
  269. ** trace buffer.
  270. ** 
  271. ** RETURNS: void.
  272. ** 
  273. ** RESTRICTIONS:
  274. ** 
  275. */
  276. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  277. #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
  278.     PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
  279. #else
  280. #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
  281. #endif
  282.  
  283. NSPR_API(void) 
  284.     PR_Trace( 
  285.         PRTraceHandle handle,       /* use this trace handle */
  286.         PRUint32    userData0,      /* User supplied data word 0 */
  287.         PRUint32    userData1,      /* User supplied data word 1 */
  288.         PRUint32    userData2,      /* User supplied data word 2 */
  289.         PRUint32    userData3,      /* User supplied data word 3 */
  290.         PRUint32    userData4,      /* User supplied data word 4 */
  291.         PRUint32    userData5,      /* User supplied data word 5 */
  292.         PRUint32    userData6,      /* User supplied data word 6 */
  293.         PRUint32    userData7       /* User supplied data word 7 */
  294. );
  295.  
  296. /* -----------------------------------------------------------------------
  297. ** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
  298. ** 
  299. ** DESCRIPTION:
  300. ** PR_SetTraceOption() controls the Trace Facility. Depending on
  301. ** command and value, attributes of the Trace Facility may be
  302. ** changed.
  303. ** 
  304. ** INPUTS:
  305. **  command: An enumerated value in the set of PRTraceOption.
  306. **  value: pointer to the data to be set. Type of the data is
  307. **  dependent on command; for each value of command, the type
  308. **  and meaning of dereferenced value is shown.
  309. **
  310. **  PRTraceBufSize: unsigned long: the size of the trace buffer,
  311. ** in bytes.
  312. ** 
  313. **  PRTraceEnable: PRTraceHandle. The trace handle to be
  314. ** enabled.
  315. ** 
  316. **  PRTraceDisable: PRTraceHandle. The trace handle to be
  317. ** disabled.
  318. ** 
  319. **  PRTraceSuspend: void. value must be NULL. All tracing is
  320. ** suspended.
  321. ** 
  322. **  PRTraceResume: void. value must be NULL. Tracing for all
  323. ** previously enabled, prior to a PRTraceSuspend, is resumed.
  324. ** 
  325. **  PRTraceStopRecording: void. value must be NULL. If recording
  326. ** (see: ** PR_RecordTraceEntries()) is being done, 
  327. ** PRTraceStopRecording causes PR_RecordTraceEntries() to return
  328. ** to its caller. If recording is not being done, this function
  329. ** has no effect.
  330. ** 
  331. **  PRTraceSuspendRecording: void. Must be NULL. If recording is
  332. ** being done, PRTraceSuspendRecording causes further writes to
  333. ** the trace file to be suspended. Data in the in-memory
  334. ** trace buffer that would ordinarily be written to the
  335. ** trace file will not be written. Trace entries will continue
  336. ** to be entered in the in-memory buffer. If the Trace Facility
  337. ** recording is already in a suspended state, the call has no
  338. ** effect.
  339. ** 
  340. **  PRTraceResumeRecording: void. value must be NULL. If
  341. ** recording for the Trace Facility has been previously been
  342. ** suspended, this causes recording to resume. Recording resumes
  343. ** with the next in-memory buffer segment that would be written
  344. ** if trace recording had not been suspended. If recording is
  345. ** not currently suspended, the call has no effect.
  346. ** 
  347. **  PRTraceLockHandles: void. value must be NULL. Locks the
  348. ** trace handle lock. While the trace handle lock is held,
  349. ** calls to PR_CreateTrace() will block until the lock is
  350. ** released.
  351. ** 
  352. **  PRTraceUnlockHandles: void. value must be NULL. Unlocks the
  353. ** trace handle lock.
  354. ** 
  355. ** OUTPUTS:
  356. **  The operation of the Trace Facility may be changed.
  357. ** 
  358. ** RETURNS: void
  359. ** 
  360. ** RESTRICTIONS:
  361. ** 
  362. */
  363. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  364. #define PR_SET_TRACE_OPTION(command,value)\
  365.     PR_SetTraceOption((command),(value))
  366. #else
  367. #define PR_SET_TRACE_OPTION(command,value)
  368. #endif
  369.  
  370. NSPR_API(void) 
  371.     PR_SetTraceOption( 
  372.         PRTraceOption command,  /* One of the enumerated values */
  373.         void *value             /* command value or NULL */
  374. );
  375.  
  376.  
  377. /* -----------------------------------------------------------------------
  378. ** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
  379. ** 
  380. ** DESCRIPTION:
  381. ** PR_GetTraceOption() retrieves the current setting of the
  382. ** Trace Facility control depending on command.
  383. ** 
  384. ** 
  385. **  PRTraceBufSize: unsigned long: the size of the trace buffer,
  386. ** in bytes.
  387. ** 
  388. ** 
  389. ** INPUTS:
  390. **  command: one of the enumerated values in PRTraceOptions
  391. ** valid for PR_GetTraceOption().
  392. ** 
  393. ** OUTPUTS:
  394. **  dependent on command.
  395. ** 
  396. ** RETURNS: void
  397. ** 
  398. ** RESTRICTIONS:
  399. ** 
  400. */
  401. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  402. #define PR_GET_TRACE_OPTION(command,value)\
  403.     PR_GetTraceOption((command),(value))
  404. #else
  405. #define PR_GET_TRACE_OPTION(command,value)
  406. #endif
  407.  
  408. NSPR_API(void) 
  409.     PR_GetTraceOption( 
  410.         PRTraceOption command,  /* One of the enumerated values */
  411.         void *value             /* command value or NULL */
  412. );
  413.  
  414. /* -----------------------------------------------------------------------
  415. ** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
  416. ** handle by name.
  417. ** 
  418. ** DESCRIPTION:
  419. ** PR_GetTraceHandleFromName() retreives an existing tracehandle
  420. ** using the name specified by qName and rName.
  421. ** 
  422. ** INPUTS:
  423. **  qName: pointer to string. QName for this trace handle. 
  424. ** 
  425. **  rName: pointer to string. RName for this trace handle. 
  426. ** 
  427. ** 
  428. ** OUTPUTS: returned.
  429. ** 
  430. ** RETURNS: 
  431. **  PRTraceHandle associated with qName and rName or NULL when
  432. ** there is no match.
  433. ** 
  434. ** RESTRICTIONS:
  435. ** 
  436. */
  437. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  438. #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
  439.     (handle) = PR_GetTraceHandleFromName((qName),(rName))
  440. #else
  441. #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
  442. #endif
  443.  
  444. NSPR_API(PRTraceHandle) 
  445.     PR_GetTraceHandleFromName( 
  446.         const char *qName,      /* QName search argument */
  447.         const char *rName       /* RName search argument */
  448. );
  449.  
  450. /* -----------------------------------------------------------------------
  451. ** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
  452. ** by bandle.
  453. ** 
  454. ** DESCRIPTION:
  455. ** PR_GetTraceNameFromHandle() retreives the existing qName,
  456. ** rName, and description for the referenced trace handle.
  457. ** 
  458. ** INPUTS: handle: PRTraceHandle.
  459. ** 
  460. ** OUTPUTS: pointers to the Trace Facility's copy of qName,
  461. ** rName and description. ... Don't mess with these values.
  462. ** They're mine.
  463. ** 
  464. ** RETURNS: void
  465. ** 
  466. ** RESTRICTIONS:
  467. ** 
  468. */
  469. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  470. #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
  471.     PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
  472. #else
  473. #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
  474. #endif
  475.  
  476. NSPR_API(void) 
  477.     PR_GetTraceNameFromHandle( 
  478.         PRTraceHandle handle,       /* handle as search argument */
  479.         const char **qName,         /* pointer to associated QName */
  480.         const char **rName,         /* pointer to associated RName */
  481.         const char **description    /* pointer to associated description */
  482. );
  483.  
  484. /* -----------------------------------------------------------------------
  485. ** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
  486. ** iterator.
  487. ** 
  488. ** DESCRIPTION:
  489. ** PR_FindNextTraceQname() retreives the first or next trace
  490. ** QName handle, depending on the value of handle, from the trace
  491. ** database. The PRTraceHandle returned can be used as an
  492. ** iterator to traverse the QName handles in the Trace database.
  493. ** 
  494. ** INPUTS:
  495. **  handle: When NULL, PR_FindNextQname() returns the first QName
  496. ** handle. When a handle is a valid PRTraceHandle previously
  497. ** retreived using PR_FindNextQname() the next QName handle is
  498. ** retreived.
  499. ** 
  500. ** OUTPUTS: returned.
  501. ** 
  502. ** RETURNS: 
  503. **  PRTraceHandle or NULL when there are no trace handles.
  504. ** 
  505. ** RESTRICTIONS:
  506. **  Iterating thru the trace handles via FindFirst/FindNext
  507. ** should be done under protection of the trace handle lock.
  508. ** See: PR_SetTraceOption( PRLockTraceHandles ).
  509. ** 
  510. */
  511. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  512. #define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
  513.     (next) = PR_FindNextTraceQname((handle))
  514. #else
  515. #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
  516. #endif
  517.  
  518. NSPR_API(PRTraceHandle) 
  519.     PR_FindNextTraceQname( 
  520.         PRTraceHandle handle
  521. );
  522.  
  523.  
  524. /* -----------------------------------------------------------------------
  525. ** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
  526. ** iterator.
  527. ** 
  528. ** DESCRIPTION:
  529. ** PR_FindNextTraceRname() retreives the first or next trace
  530. ** RName handle, depending on the value of handle, from the trace
  531. ** database. The PRTraceHandle returned can be used as an
  532. ** iterator to traverse the RName handles in the Trace database.
  533. ** 
  534. ** INPUTS:
  535. **  rhandle: When NULL, PR_FindNextRname() returns the first
  536. ** RName handle. When a handle is a valid PRTraceHandle
  537. ** previously retreived using PR_FindNextRname() the next RName
  538. ** handle is retreived.
  539. **  qhandle: A valid PRTraceHandle retruned from a previous call
  540. ** to PR_FIND_NEXT_TRACE_QNAME().
  541. ** 
  542. ** OUTPUTS: returned.
  543. ** 
  544. ** RETURNS: 
  545. **  PRTraceHandle or NULL when there are no trace handles.
  546. ** 
  547. ** RESTRICTIONS:
  548. **  Iterating thru the trace handles via FindNext should be done
  549. ** under protection of the trace handle lock. See: (
  550. ** PR_SetTraceOption( PRLockTraceHandles ).
  551. ** 
  552. */
  553. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  554. #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
  555.     (next) = PR_FindNextTraceRname((rhandle),(qhandle))
  556. #else
  557. #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
  558. #endif
  559.  
  560. NSPR_API(PRTraceHandle) 
  561.     PR_FindNextTraceRname( 
  562.         PRTraceHandle rhandle,
  563.         PRTraceHandle qhandle
  564. );
  565.  
  566. /* -----------------------------------------------------------------------
  567. ** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
  568. ** 
  569. ** DESCRIPTION:
  570. ** PR_RecordTraceEntries() causes entries in the in-memory trace
  571. ** buffer to be written to external media.
  572. **
  573. ** When PR_RecordTraceEntries() is called from an application
  574. ** thread, the function appears to block until another thread
  575. ** calls PR_SetTraceOption() with the PRTraceStopRecording
  576. ** option. This suggests that PR_RecordTraceEntries() should be
  577. ** called from a user supplied thread whose only job is to
  578. ** record trace entries. 
  579. ** 
  580. ** The environment variable NSPR_TRACE_LOG controls the operation
  581. ** of this function. When NSPR_TRACE_LOG is not defined in the
  582. ** environment, no recording of trace entries occurs. When
  583. ** NSPR_TRACE_LOG is defined, the value of its definition must be
  584. ** the filename of the file to receive the trace entry buffer.
  585. **
  586. ** PR_RecordTraceEntries() attempts to record the in-memory
  587. ** buffer to a file, subject to the setting of the environment
  588. ** variable NSPR_TRACE_LOG. It is possible because of system
  589. ** load, the thread priority of the recording thread, number of
  590. ** active trace records being written over time, and other
  591. ** variables that some trace records can be lost. ... In other
  592. ** words: don't bet the farm on getting everything.
  593. ** 
  594. ** INPUTS: none
  595. ** 
  596. ** OUTPUTS: none
  597. ** 
  598. ** RETURNS: PR_STATUS
  599. **    PR_SUCCESS no errors were found.
  600. **    PR_FAILURE errors were found.
  601. ** 
  602. ** RESTRICTIONS:
  603. ** Only one thread can call PR_RecordTraceEntries() within a
  604. ** process.
  605. ** 
  606. ** On error, PR_RecordTraceEntries() may return prematurely.
  607. ** 
  608. */
  609. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  610. #define PR_RECORD_TRACE_ENTRIES()\
  611.     PR_RecordTraceEntries()
  612. #else
  613. #define PR_RECORD_TRACE_ENTRIES()
  614. #endif
  615.     
  616. NSPR_API(void)
  617.     PR_RecordTraceEntries(
  618.         void 
  619. );
  620.  
  621. /* -----------------------------------------------------------------------
  622. ** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
  623. ** the Trace Facility
  624. ** 
  625. ** DESCRIPTION:
  626. ** PR_GetTraceEntries() retreives trace entries from the Trace
  627. ** Facility. Up to count trace entries are copied from the Trace
  628. ** Facility into buffer. Only those trace entries that have not
  629. ** been copied via a previous call to PR_GetTraceEntries() are
  630. ** copied. The actual number copied is placed in the PRInt32
  631. ** variable pointed to by found.
  632. **
  633. ** If more than count trace entries have entered the Trace
  634. ** Facility since the last call to PR_GetTraceEntries() 
  635. ** a lost data condition is returned. In this case, the most
  636. ** recent count trace entries are copied into buffer and found is
  637. ** set to count.
  638. ** 
  639. ** INPUTS:
  640. **  count. The number of trace entries to be copied into buffer.
  641. ** 
  642. ** 
  643. ** OUTPUTS:
  644. **  buffer. An array of PRTraceEntries. The buffer is supplied
  645. ** by the caller.
  646. ** 
  647. ** found: 32bit signed integer. The number of PRTraceEntries
  648. ** actually copied. found is always less than or equal to count.
  649. ** 
  650. ** RETURNS: 
  651. **  zero when there is no lost data.
  652. **  non-zero when some PRTraceEntries have been lost.
  653. ** 
  654. ** RESTRICTIONS:
  655. ** This is a real performance pig. The copy out operation is bad
  656. ** enough, but depending on then frequency of calls to the
  657. ** function, serious performance impact to the operating
  658. ** application may be realized. ... YMMV.
  659. ** 
  660. */
  661. #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
  662. #define PR_GET_TRACE_ENTRIES(buffer,count,found)\
  663.         PR_GetTraceEntries((buffer),(count),(found))
  664. #else
  665. #define PR_GET_TRACE_ENTRIES(buffer,count,found)
  666. #endif
  667.  
  668. NSPR_API(PRIntn)
  669.     PR_GetTraceEntries(
  670.         PRTraceEntry    *buffer,    /* where to write output */
  671.         PRInt32         count,      /* number to get */
  672.         PRInt32         *found      /* number you got */
  673. );
  674.  
  675. PR_END_EXTERN_C
  676.  
  677. #endif /* prtrace_h___ */
  678.  
  679.